Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 5 - Menu Manager Reference / Menu Manager Functions

Creating Menus /

GetMenu

CHANGED WITH THE APPEARANCE MANAGER

Creates a menu according to the specified menu and extended menu resources.

pascal MenuHandle GetMenu (short resourceID);

resourceID

The resource ID of the menu and extended menu that defines the characteristics of the menu. (You usually use the same number for a menu's resource ID as the number that you specify for the menu ID in the menu resource.)

function result

Returns a handle to the menu structure for the menu. You can use the returned menu handle to refer to this menu in most Menu Manager functions. If GetMenu is unable to read the menu or menu definition function from the resource file, GetMenu returns nil.

DISCUSSION

In addition to creating a menu, the GetMenu function also creates a menu structure for the menu. GetMenu reads the menu definition function into memory (if not already present) and stores a handle to the menu definition function in the menu structure. GetMenu does not insert the newly created menu into the current menu list.

Note

You typically use the GetMenu function only when you create submenus; you can create all your pull-down menus at once using the function GetNewMBar, and you can create pop-up menus using the standard pop-up menu button control definition function.

After reading the 'MENU' resource, GetMenu searches for an extended menu resource and an 'mctb' resource with the same resource ID as the 'MENU' resource. If the specified 'mctb' resource exists, GetMenu uses SetMCEntries to add the entries defined by the resource to the application's menu color information table. If the 'mctb' resource does not exist, GetMenu uses the default colors specified in the menu bar entry of the application's menu color information. If neither a menu bar entry nor a 'mctb' resource exists, GetMenu uses the standard colors for the menu.

Storing the definitions of your menus in resources (especially menu titles and menu items) makes your application easier to localize.

WARNING

Menus in a resource must not be purgeable nor should the resource lock bit be set. Do not define a "circular" hierarchical menu--that is, a hierarchical menu in which a submenu has a submenu whose submenu is a hierarchical menu higher in the chain.

SPECIAL CONSIDERATIONS

To release the memory associated with a menu that you created using GetMenu, first call DeleteMenu to remove the menu from the current menu list and to remove any entries for this menu in your application's menu color information table; then call DisposeMenu to dispose of the menu structure. After disposing of a menu, use DrawMenuBar to update the menu bar.

WHEN THE APPEARANCE MANAGER IS NOT AVAILABLE

The extended menu resource is not available.